home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 3: CDPD 3
/
Almathera Ten on Ten - Disc 3: CDPD3.iso
/
fish
/
676-700
/
699
/
ezasm
/
ezlib.doc
< prev
next >
Wrap
Text File
|
1995-03-18
|
10KB
|
421 lines
ez.lib Version 1.3 by Joe Siebenmann
DISCLAIMER:
You have the right to freely use, copy and distribute this program
as long as the following conditions are met:
1. The documentation is included with the program, and neither
is modified in any way.
2. The program is not included in any package for profit
unless written consent from the author is obtained.
Inclusion in a PD series is OK as long as the charge
( for disk, copying etc. ) is REASONABLE.
NOTE: The author does not accept any responsibility for any damage
that might result from the use of this program.
--- New for Version 1.3 ---
o All function arguments are now pushed onto the stack to avoid
register corruption.
o New function sprint( ), replaces ItoA( ). Works just like
C's sprintf().
o Print( ) and KPrint( ) improved! No more PrintInit( ) and
PrintClose( )! Now accepts multiple DataStream arguments!
( also sprint( ) )
Ez.lib is a scanned library consisting of object files which are
individually loaded if there is an external reference to one of them.
Many "c.lib" like functions are included which are not normally available
with assembly language. With these functions, EZAsm can be used
for a much wider range of programming applications.
WARNING:
Since some of these functions write characters into memory locations,
they have the potential to cause disastrous results. Always make
sure your "strings" are null terminated, and your address registers
are pointing to the right address.
*********************
* Print Functions *
*********************
Usage: Print( FormatString DataStream []... )
KPrint( FormatString DataStream []... )
Performs C-like formatting of the data stream.
Where % formatting commands are found in the FormatString, they're
replaced with the corresponding element(s) in the DataStream.
Print( ) outputs the results to the current output handle.
KPrint( ) is like Kprintf() in that it sends its output
out the serial port at 9600 baud, where if you have another computer
running a terminal program, and hooked up with a null modem cable,
all the output can be captured and reviewed, even if your program is
taking over the machine, or crashes! This is a fantastic debugging tool!
More FormatString options and information can be found by looking up
RawDoFmt() ( ExecBase ) which this uses.
FormatString
A C-like null terminated format string,
with these % options:
%[length]type
length - data size: 'l' for LONG ( WORD is the default size )
( BYTE data MUST be moved to a WORD or LONG for display )
type - types supported:
d - decimal
x - hexadecimal
s - string
c - character
DataStream
Accepts multiple variable names, registers or constants.
Constant data ( 2, $f4, '#', etc. ) is pushed as LONG, so use 'l'.
( %ld %lx %lc )
Examples:
Print( "Hello, World!\n" * )
Print( "word %ld = %s\n" 1 "YHWH" )
KPrint( "foo = %08lx D2 = %08lx\n" foo d2 )
A 200 byte buffer for K/Print( ) is allocated on the stack frame
( at .pbuf ) so no AllocMem( ) is needed. Be careful when using "%s"
and printing large strings, as this can overflow the buffer and
trash your variables.
Print( ) needs the current output handle, and _DosBase,
and will get these automatically. "OutHandle" will contain
the current output handle, and is available for use.
o EZAsm supports argument strings surrounded by double quotes.
Strings are automatically null terminated.
The following C character constants are supported:
\b backspace
\f form feed
\n newline
\r carriage return
\t horizontal tab
\v vertical tab
*************************
* Character Functions *
*************************
Usage: [!] is.....( StringPointer ) {
.
.
}
[!] is.....( StringPointer ) {
.
.
} else {
.
.
}
[!] is.....( StringPointer ) label
Looks at the character ( byte ) at StringPointer address and,
if the test is satisfied, performs the TRUE action.
These C-like functions are supported:
isalnum( ) alphabetic or digit character?
isalpha( ) alphabetic character?
isascii( ) ASCII character? ( $0-$7f )
iscntrl( ) control character? ( $0-$1f or $7f )
isdigit( ) digit character?
isgraph( ) graphics character? ( $21-$7e )
islower( ) lowercase letter?
isprint( ) printable character? ( including space )
ispunct( ) punctuation character?
isspace( ) white space character? ( $20 $09-$0c )
isupper( ) uppercase letter?
isxdigit( ) hexadecimal digit character?
********************
* String Compare *
********************
Usage: [result =] strcmp( String1 String2 )
[result =] strncmp( String1 String2 Length )
[!] str...( String1 String2 ) {
.
.
}
[!] str...( String1 String2 ) {
.
.
} else {
.
.
}
[!] str...( String1 String2 ) label
Compares strings String1 and String2 ( for strncmp( ), at most,
Length characters are compared ) The return value is -1 if String1
was less, 1 if String1 was greater, and 0 if String1 and String2
match exactly.
The zero or non-zero result in D0 "sets" the Z flag.
Its the state of this flag that determines what action is taken.
As with the C versions, a non-zero result will perform the TRUE
action. The most common test is for strings being equal, so "!"
must be used to "flip" the zero result. To test for not equal
omit the "!". Use the "result =" form to save the result
for specific condition testing or just test D0.
*********************
* Data Conversion *
*********************
Usage: D0 = AtoI( StrAddr FormatString )
Converts ASCII digit characters found at StrAddr, according to
the format specified by FormatString, and places the result in D0.
Conversion is stopped when a non-valid digit character is found.
Buffer
Address of first ASCII digit character.
FormatString
"%d" convert [signed] decimal number
"%x" convert hexadecimal number
----------------------------------------------
Usage: sprint( Buffer FormatString DataStream []... )
Performs C-like formatting of the data stream.
Where % formatting commands are found in the FormatString, they're
replaced with the corresponding element(s) in the DataStream.
The result is placed in Buffer.
More FormatString options and information can be found by looking up
RawDoFmt() ( ExecBase ) which this uses.
Buffer
Address of buffer large enough to hold the resulting string.
FormatString
A C-like null terminated format string,
with these % options:
%[length]type
length - data size: 'l' for LONG ( WORD is the default size )
( BYTE data MUST be moved to a WORD or LONG )
type - types supported:
d - decimal
x - hexadecimal
s - string
c - character
DataStream
Accepts multiple variable names, registers or constants.
Constant data ( 2, $f4, '#', etc. ) is pushed as LONG, so use 'l'.
( %ld %lx %lc )
Example:
sprint( Buf "\t\tmove%s\t#%ld,d1\n" ".l" 0 )
( see Mk.s for more examples )
**********************
* String Functions *
**********************
Usage: [location =] search( StrAddr String )
Searches for the first occurance of String starting at
StrAddr. If a match is found, the address of the first
matching byte from StrAddr is returned in D0, otherwise D0 = 0.
( Use this function when searching for two or more characters
( strchr( ) is better for single character searches ))
----------------------------------------
Usage: insert( StrAddr String )
Inserts String ( excluding null byte ) starting at
StrAddr ( address returned by a previous string search function etc. ).
( buffer at StrAddr must be large enough to hold the extra bytes )
*********************************
* Standard C string functions *
*********************************
Usage: [location =] strcat( StrAddr String )
Concatenates character string String to the end of StrAddr,
placing a null byte at the end of the final string.
Returns ( original ) address of StrAddr in D0.
----------------------------------------
Usage: [location =] strchr( StrAddr Char )
Searches at StrAddr for the first occurance of character Char.
If it's found, the address of the character is
returned in D0, otherwise D0 = 0.
( be sure the actual character value is loaded into Char, not
its address ( use: #'x' ))
----------------------------------------
Usage: [location =] strcpy( StrAddr String )
Copies String to StrAddr, returning ( original ) addr of StrAddr
in D0.
----------------------------------------
Usage: [length =] strlen( StrAddr )
Returns the number of characters at StrAddr, excluding the
null byte in D0.
----------------------------------------
Usage: [location =] strncat( StrAddr String Length )
Concatenates character string String to the end of StrAddr,
until either the null byte is reached, or Length bytes have been
concatenated, whichever occurs first. Returns ( original ) addr
of StrAddr in D0.
----------------------------------------
Usage: [location =] strncpy( StrAddr String Length )
Copies String to StrAddr until either the null byte is reached,
or Length bytes have been copied, whichever occurs first.
Returns ( original ) addr of StrAddr in D0.
----------------------------------------
Usage: [location =] strrchr( StrAddr Char )
Searches at StrAddr for the last occurance of the character Char.
If found, its address is returned in D0, otherwise D0 = 0.
( be sure the actual character value is loaded into Char, not
its address ( use: #'x' ))
----------------------------------------
Enjoy!